home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48_2 / tools.exe / DOCS / RPLCOMP.DOC < prev    next >
Text File  |  1991-07-19  |  16KB  |  529 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                    Instructions for MS-DOS program "RPLCOMP"
  9.  
  10.        *****************************************************************
  11.  
  12.                                      NOTICE
  13.  
  14.        Hewlett-Packard is making RPLCOMP.EXE available to customers free
  15.        of charge to help them in HP 48SX application development, under
  16.        the following conditions:
  17.  
  18.  
  19.        *  The program RPLCOMP.EXE and the documentation file RPLCOMP.MAN
  20.           are provided "as is," and are subject to change without notice.
  21.           Hewlett-Packard Company make no warranty of any kind with
  22.           regard to the software or documentation, including, but not
  23.           limited to, the implied warranties of merchantability and
  24.           fitness for a particular purpose.  Hewlett-Packard Company
  25.           shall not be liable for any error or for incidental or
  26.           consequential damages in connection with the furnishing,
  27.           performance, or use of this software and documentation.
  28.  
  29.  
  30.        *  The program and documentation are copyrighted by Hewlett-
  31.           Packard.  Sale of this material is prohibited without prior
  32.           written permission of Hewlett-Packard Company.
  33.  
  34.  
  35.        *  The HP Customer Support department does not support RPLCOMP.
  36.           Questions, comments, defect reports, etc. should be directed to
  37.           the Library Development conference on the HP Calculator
  38.           Bulletin Board System.  All responses from Hewlett-Packard will
  39.           normally be provided through that conference.
  40.  
  41.  
  42.        *  Software generated by RPLCOMP.EXE should be tested and
  43.           qualified in its final form.
  44.  
  45.        Revised versions of the software and documentation will be posted
  46.        on the Bulletin Board as they become available.
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                    -1-
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.        1.  RPLCOMP - RPL Compiler
  75.  
  76.        Rplcomp is an RPL compiler or, more precisely, a preprocessor.
  77.        From RPL source files, it produces sasm source files ready for
  78.        assembly.
  79.  
  80.        The compiler is invoked as follows:
  81.  
  82.          rplcomp [ -C ] [ <inputfile> [ <outputfile> [ <extfile> ] ] ]
  83.  
  84.        Rplcomp accepts up to 3 arguments:
  85.  
  86.        <inputfile>    Specifies the RPL source.  If omitted or specified
  87.                       as ``-'', it defaults to stdin. RPL source file
  88.                       names by convention use the ``.s'' extension.
  89.  
  90.        <outputfile>   Specifies where the output will go, defaulting to
  91.                       stdout.  Since the output is usually fed to sasm,
  92.                       RPL output file names by convention use the ``.a''
  93.                       extension.
  94.  
  95.        <extfile>      Specifies the file containing information for the
  96.                       hash table, so named because the customary
  97.                       extension is ``.ext''.  If this parameter is
  98.                       omitted, this information is not output.  If this
  99.                       paramater is specified as ``-'', the information is
  100.                       output to stdout.
  101.  
  102.        The -C option copies the RPL source as comments in the output
  103.        code.  This allows a post-processor to edit the assembly listings
  104.        in a more readable format.
  105.  
  106.  
  107.        1.1  Object Definition
  108.  
  109.  
  110.        When rplcomp is compiling a file, it recognizes certain words
  111.        (detailed below) and generates appropriate code for them.  All
  112.        other words are assumed to be the labels of objects in the
  113.        runstream, and are emitted simply as 5-nibble constants, possibly
  114.        with substitution as per DEFINE below.  After assembly, the SLOAD
  115.        program will be used to fill in the addresses of the objects in
  116.        the runstream based on the provided list of entry points called
  117.        ENTRIES.O.
  118.  
  119.        The following sections describes the words recognized by rplcomp,
  120.        and their corresponding actions.
  121.  
  122.        The following words define objects:
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                    -2-
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.        LAM <lamid>
  141.           Defines a DOLAM object whose name is specified by <lamid>.  The
  142.           non-ASCII escape sequences listed under $ below are allowed.
  143.           <_l_a_m_i_d> may be a DEFINED value (See DEFINE below).
  144.  
  145.        ID <id>
  146.           Defines a DOIDNT object whose name is specified by <id>.  <_i_d>
  147.           may be a DEFINED value (See DEFINE below).
  148.  
  149.        TAG <tagid> <object>
  150.           Defines a DOTAG object whose tag is specified by <tagid> and
  151.           whose object is given by <object>.  <object> may be either an
  152.           object definition or a label.  < tagid > may be a DEFINED value
  153.           (See DEFINE below).
  154.  
  155.        $ "string"
  156.        "string"
  157.           Defines a DOCSTR object with the contents contained between the
  158.           quotes.  Two consecutive quotes within the string are
  159.           interpreted as a single quote (e.g., ``""""'' becomes the
  160.           string ``f(CW"'').  Non-ASCII characters may be input as \xx
  161.           where xx is the hex value of the character.  Also, \n, \r, \f,
  162.           \t are the ASCII newline, return, form-feed, and tab
  163.           characters.
  164.  
  165.        CHR <char>
  166.        CHR ^<char>
  167.        CHR "<char>"
  168.        CHR "^<char>"
  169.           Defines a DOCHAR object with the specified character.  The
  170.           second and fourth forms generate control characters.  For
  171.           example, ``CHR A'' generates an ``A'', ``CHR ^A'' generates a
  172.           control-A.  The double-quote character can be generated by
  173.           specifying ``CHR "'' or ``CHR """''.  Also, the \-escaped
  174.           characters described under $ above can be used.
  175.  
  176.        CODE
  177.        ...(assembly language code)...
  178.        ENDCODE
  179.           For insertion of assembly-language code in a DOCODE object.
  180.           The word CODE generates a DOCODE and a link field, the word
  181.           ENDCODE terminates assembly-language input and generates a
  182.           label to be used by the link field.  When encountered in the
  183.           assembly-language code, the word LOOP results in generation of
  184.           RPL main loop code.  The words LOOP and ENDCODE are recognized
  185.           by rplcomp if they are either 1) the first word on the line, or
  186.           2) the second word preceded by a label.
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                    -3-
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.        # <hex number>
  207.        #<hex number>
  208.        <dec number>
  209.           Defines a DOBINT object whose body is the number specified in
  210.           hex or in decimal.  Rplcomp recognizes lower-case hex digits;
  211.           compiler does not.
  212.  
  213.        <real number>
  214.        % <real number>
  215.           Defines a DOREAL object with the specified floating-point
  216.           number.  To be recognized as a real number in the first form,
  217.           the number must contain a decimal point and/or ``E''.  The
  218.           second form is more forgiving, and will recognize an integer as
  219.           a real number.
  220.  
  221.        %% <extended real number>
  222.           Defines a DOEREL object with the specified floating-point
  223.           number.
  224.  
  225.        C% <real number> <real number>
  226.           Defines a DOCMP object with the specified floating-point
  227.           numbers.
  228.  
  229.        C%% <extended real number> <extended real number>
  230.           Defines a DOECMP object with the specified floating-point
  231.           numbers.
  232.  
  233.        PTR <label>
  234.           Forces the <label> to be entered as a runstream object.
  235.  
  236.        ROMPTR <hex #> <hex #>
  237.        ROMPTR <label>
  238.           Defines a DOROMP object with the two 3-digit (maximum) hex
  239.           numbers.  If <label> is present, forms a DOROMP object for that
  240.           label (resolved by the linker).
  241.  
  242.        ARRY [ obj ... ]
  243.        ARRY dim ... [ obj ... ]
  244.        LNKARRY [ obj ... ]
  245.        LNKARRY dim ... [ obj ... ]
  246.           Defines a DOARRY or DOLNKARRY object with the following
  247.           characteristics: If dim ... is present, the array will be set
  248.           up with the given dimensionality.  If no dimensions are
  249.           present, a linear array will be constructed to contain the list
  250.           of objects.
  251.  
  252.           At least one object must always be specified because the
  253.           element type is determined from the object.  The list of
  254.           objects will occupy element positions in order.  For an ARRY,
  255.           every object position must have an object; in LNKARRYs, object
  256.           positions may be left blank by using _ as a placeholder, and by
  257.  
  258.  
  259.  
  260.                                    -4-
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.           dimensioning the array larger than the object list.
  273.  
  274.           Array objects must be object definitions; pointers to objects
  275.           are not supported by RPL.
  276.  
  277.        HXS <length in hex> <string>
  278.        HXS 0
  279.        GROB <length in hex> <string>
  280.        GROB 0
  281.           Defines a DOHSTR or DOGROB object with the specified hex
  282.           string.  If the string contains fewer nibbles than specified by
  283.           the length, the hex string will be padded with leading zeroes.
  284.           (This is a departure from compiler, which padded with trailing
  285.           zeroes.)
  286.  
  287.           If the length is zero, HXS does not take a second argument.
  288.  
  289.        CONTROL STRUCTURES
  290.  
  291.        The following words generate RPL control words.  In addition,
  292.        rplcomp tracks, on an internal stack, the use of these words to
  293.        ensure that all opening control words (such as ``::'') are matched
  294.        by closing control words (such as ``;'').
  295.  
  296.        When non-structured programming techniques are being used, or
  297.        unrecognized control words are used, this behavior can be defeated
  298.        in two ways:  1) If the control word is surrounded by parentheses,
  299.        rplcomp performs the appropriate internal stack operations but
  300.        does not emit any code; 2) If the control word is surrounded by
  301.        square brackets, the control word label is compiled, and rplcomp
  302.        does not perform the associated internal stack operations.
  303.  
  304.        Examples:
  305.        1)
  306.           -1 The sequence ``DO [LOOP] LOOP'' will emit DO, LOOP, and
  307.          LOOP, but will not consider the second ``LOOP'' to be unmatched.
  308.        2)
  309.           -1 The sequence ``ONE_DO (DO) LOOP'' will emit ONE_DO and LOOP,
  310.          and will not consider the ``LOOP'' to be unmatched.
  311.  
  312.        This feature, an enhancement over compiler, can be applied to all
  313.        control words except FCN.
  314.  
  315.        The RPL control words recognized by rplcomp are:
  316.  
  317.        :: ...(RPLcode)...  ;
  318.           The word ``::'' generates DOCOL, the word ``;'' generates SEMI.
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                    -5-
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.        BEGIN ...(RPLcode)... AGAIN
  339.        BEGIN ...(RPLcode)... UNTIL
  340.        BEGIN ...(RPLcode)... WHILE ...(RPLcode)... REPEAT
  341.           These words generate the appropriate RPL words.  The RPL code
  342.           between WHILE and REPEAT is sandwiched between a DOCOL and a
  343.           SEMI.
  344.  
  345.        DO ...(RPLcode)... LOOP
  346.        DO ...(RPLcode)... +LOOP
  347.           These words generate the appropriate RPL words.
  348.  
  349.        IF ...(THENclause)... THEN
  350.        IF ...(THENclause)... ELSE ...(ELSEclause)... THEN
  351.           These words generate the appropriate combinations of quotes,
  352.           DOCOLs, SEMIs, RPITs, and RPITEs to emulate the corresponding
  353.           FORTH words.
  354.  
  355.        FCN { ...(list of LAM ids)... } ...(RPLcode)... ENDFCN
  356.           Generates a list of LAMs, BIND, and ABND for writing an RPL
  357.           function.  The sequence:
  358.            .5 FCN { A B C } ...(RPLcode)... ENDFCN
  359.            .5 is equivalent to:
  360.            .5 { LAM A LAM B LAM C } BIND ...(RPLcode)... ABND
  361.  
  362.        { ...(RPLcode)... }
  363.           The words ``{'' and ``}'' delimit a list, generating the words
  364.           DOLIST and SEMI (respectively).
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                    -6-
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.        1.2  Miscellaneous RPL Operations
  405.  
  406.  
  407.        The following words are recognized by rplcomp:
  408.  
  409.        ASSEMBLE
  410.        ...(assembly language code)...
  411.        RPL
  412.           For insertion of assembly-language code.  When encountered in
  413.           the assembly-language code, the word LOOP results in generation
  414.           of RPL main loop code.  The words LOOP and RPL are recognized
  415.           by rplcomp if they are either 1) the first word on the line, or
  416.           2) the second word preceded by a label.
  417.  
  418.        ( ...(comments)... )
  419.        * ...(comment text)...
  420.           A left-parenthesis token begins a comment.  The comment is
  421.           terminated immediately when a right-parenthesis is encountered
  422.           - the right-parenthesis need not be surrounded by white space
  423.           (this peculiar behavior is to provide compatibility with
  424.           compiler).  This form of comment cannot occur within a multi-
  425.           token sequence (e.g., HXS ( this is a hex string ) 5 12345 is
  426.           unacceptable).  Lines beginning with an asterisk in the first
  427.           column are output untouched as comment lines.
  428.  
  429.        ROMID <internal hexROMid>
  430.        xROMID <external hexROMid>
  431.        NAME <label>
  432.        NULLNAME <label>
  433.        xNAME <label>
  434.        sNAME <label> <string>
  435.        tNAME <label> <string>
  436.           These directives generate labels and information needed for
  437.           parsing and decompiling of keywords.  ROMID specifies a ROM ID
  438.           to be used for the name directives.  xROMID specifies a ROM ID
  439.           and indicates that any objects defined in this file should be
  440.           referenced by DOROMP objects.
  441.  
  442.           The various name directives generate global labels, code, and
  443.           information for the .ext file needed for parsing and
  444.           decompiling.  The differences lie in the creation of the hash
  445.           entry (the name by which the user identifies the object) and
  446.           the label (the name by which the assembler and linker know the
  447.           object):
  448.               NAME - the global label and hash name are the same.
  449.               xNAME - the global label is the hash name with 'x'
  450.           prefixed.
  451.               sNAME - the global label and hash entry are independently
  452.           specified.
  453.               tNAME - specifies that an additional hash name belongs to
  454.           the given label.
  455.  
  456.  
  457.  
  458.                                    -7-
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.               NULLNAME - no hash entry is provided.
  471.  
  472.           These words also allow the rompart generator to produce the
  473.           appropriate values for use in ROMPTRs, etc.
  474.  
  475.           If the xROMID has been given, references to the labels will
  476.           produce DOROMP objects instead of ROM pointers.
  477.  
  478.        NAMELESS <label>
  479.        LABEL <label>
  480.        LOCALNAME <label>
  481.        LOCALLABEL <label>
  482.           NAMELESS and LABEL simply generate global labels.  LOCALNAME
  483.           and LOCALLABEL generate local labels.
  484.  
  485.        EXTERNAL <label>
  486.        LOCAL <label>
  487.           These words declare characteristics of the following label:
  488.           EXTERNAL will cause all future references to its label to
  489.           generate DOROMP objects; LOCAL will cause future references to
  490.           its label to be local, not global.
  491.  
  492.        DEFINE <label1> <label2>
  493.           This allows the substitution of one object label for another.
  494.           It may also be used in LAMs to allow a long identifier in the
  495.           source code, while using a short identifier in the compiled
  496.           output.
  497.  
  498.        INCLUDE <filename>
  499.           This allows the text of <filename> to be interpolated into the
  500.           source at this line.  After compiling the included file,
  501.           compilation will resume at the start of the next line.
  502.           INCLUDEs may be nested.
  503.  
  504.        TITLE ...(title text)...
  505.        STITLE ...(subtitle text)...
  506.        EJECT
  507.           These directives generate TITLE, STITLE, and EJECT commands for
  508.           the assembler.  The text for TITLE and STITLE is comprised of
  509.           the remainder of the line.
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.                                    -8-
  525.  
  526.  
  527.  
  528.  
  529.